ROS 2 Humble installation guide

Copyright © Quectel Wireless Solutions Co., Ltd. 2026. All rights reserved.

---

This document is intended for developers, system integrators, and field deployment teams building customized ROS 2 Humble runtime on the Quectel Pi H1 platform or similar Debian 13 (Trixie) environments. It covers the complete workflow from source code synchronization, dependency preparation, compilation troubleshooting, to environment variable configuration and communication testing. Through this guide, you can:

• Obtain an installation process optimized for industrial/robotics scenarios, quickly establishing a tailorable ROS 2 Humble development environment;

• Understand common issues and solutions for handling dependency conflicts and avoiding commercial middleware like Fast DDS/Connext on clean Debian systems;

• Build a reproducible workspace structure, providing a unified template for CI, automated deployment, or multi-device synchronization;

• Verify C++/Python node interoperability based on the included example tests, ensuring the environment is ready for subsequent application development.

Prerequisites

• Operating System: Debian 13 (Trixie)

• Network: Stable internet connection for downloading dependencies and source code

• Storage and time: At least 10GB free space, 1-3 hours (depending on performance and network)

• Python: Python 3.10/3.11 is recommended (3.12+ may have compatibility issues)

• Other recommendations: Update the system in advance: sudo apt-get update && sudo apt-get full-upgrade

Installation steps

• Install basic dependency packages

    sudo apt-get update && sudo apt-get full-upgrade
    sudo apt-get install -y \
    python3-flake8-blind-except \
    python3-flake8-class-newline \
    python3-flake8-deprecated \
    python3-mypy \
    python3-pip \
    python3-pytest \
    python3-pytest-cov \
    python3-pytest-mock \
    python3-pytest-repeat \
    python3-pytest-rerunfailures \
    python3-pytest-runner \
    python3-pytest-timeout \
    python3-rosdep2 \
    python3-colcon-core \
    vcstool \
    build-essential \git

• Create ROS 2 workspace

mkdir -p ~/ros2_humble
cd ~/ros2_humble

• Get ROS 2 Humble source code

cd ~/ros2_humble
mkdir -p src
wget https://raw.githubusercontent.com/ros2/ros2/humble/ros2.repos
vcs import src < ros2.repos

• Install system dependencies

sudo rosdep init
rosdep update
rosdep install --from-paths src --ignore-src --rosdistro humble -y -r \
  --skip-keys "fastcdr rti-connext-dds-6.0.1 urdfdom_headers python3-vcstool \
              ignition-math6 ignition-cmake2 ignition-common3 ignition-transport8"

• Skipped packages explanation

  • fastcdr, rti-connext-dds-6.0.1: Commercial/optional dependencies

  • urdfdom_headers, python3-vcstool: May have been installed through other means

  • ignition-math6, ignition-cmake2, ignition-common3, ignition-transport8: Not available in Debian 13 (Gazebo-related, not core functionality)

• Common errors (can be ignored)

  • python3-sip-dev failure: Dependency for GUI tools (rqt), does not affect core functionality

  • python3-nose failure: Deprecated in Python 3.12+, does not affect core functionality

• Compile source code

colcon build --symlink-install

• Issues that may be encountered during compilation

  • Issue 1: Fast DDS related errors
    - Error message:

    Starting >>> rmw_connextdds
    --- stderr: rmw_fastrtps_shared_cpp
    CMake Deprecation Warning at CMakeLists.txt:15 (cmake_minimum_required):
      Compatibility with CMake < 3.10 will be removed from a future version of
      CMake.
    
      Update the VERSION argument <min> value.  Or, use the <min>...<max> syntax
      to tell CMake that the project requires at least <min> but has been updated
      to work with policies introduced by <max> or earlier.
    
    CMake Error at CMakeLists.txt:47 (find_package):
      Could not find a package configuration file provided by "fastrtps"
      (requested version 2.6.2) with any of the following names:
    
        fastrtpsConfig.cmake
        fastrtps-config.cmake
    
      Add the installation prefix of "fastrtps" to CMAKE_PREFIX_PATH or set
      "fastrtps_DIR" to a directory containing one of the above files.  If
      "fastrtps" provides a separate development package or SDK, be sure it has
      been installed.
    
    ---
    Failed   <<< rmw_fastrtps_shared_cpp [2.60s, exited with code 1]
    

    - Cause: The package `rmw_fastrtps_shared_cpp` depends on Fast DDS (fastrtps). Fast DDS is not installed, so CMake cannot find fastrtpsConfig.cmake, resulting in the error. Even if you plan to use Cyclone DDS, colcon will still attempt to build Fast DDS related packages unless explicitly skipped.  
    - Solution: When using Cyclone DDS, directly skip the Fast DDS series packages:  
    

      cd ~/ros2_humble
      export RMW_IMPLEMENTATION=rmw_cyclonedds_cpp
      colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release \
      --packages-skip \
      rmw_fastrtps_shared_cpp rmw_fastrtps rmw_fastrtps_cpp rmw_fastrtps_dynamic_cpp \
      rmw_connextdds rmw_connextdds_common rmw_connextddsmicro \
      rmw_implementation
    

  • Issue 2: rmw_implementation build failure
    - Error message:

    Starting >>> rmw_implementation
    [-1762327992435806464.000s] ERROR:colcon.colcon_cmake.task.cmake.build:Failed to find the following files:
    -/home/root/ros2_humble/install/rmw_fastrtps_shared_cpp/share/rmw_fastrtps_shared_cpp/package.sh
    - /home/root/ros2_humble/install/rmw_fastrtps_cpp/share/rmw_fastrtps_cpp/package.sh
    -/home/root/ros2_humble/install/rmw_fastrtps_dynamic_cpp/share/rmw_fastrtps_dynamic_cpp/package.sh
    Check that the following packages have been built:
    - rmw_fastrtps_shared_cpp
    - rmw_fastrtps_cpp
    - rmw_fastrtps_dynamic_cpp
    Failed   <<< rmw_implementation [0.40s, exited with code 1]
    

    - Cause: The build system will look for the environment hooks of the Fast DDS family by default (the package.sh files of rmw_fastrtps_* under install). Fast DDS is not installed, so these files cannot be found, causing rmw_implementation, rcl, etc. to fail.  
    - Solution:  
            - Explicitly select Cyclone DDS: `export RMW_IMPLEMENTATION=rmw_cyclonedds_cpp`  
            - Hide Fast DDS/Connext source packages (to avoid subsequent scanning):  
      ```bash
      for d in \
        src/**/rmw_fastrtps_shared_cpp \
        src/**/rmw_fastrtps_cpp \
        src/**/rmw_fastrtps_dynamic_cpp \
        src/**/rmw_connextdds \
        src/**/rmw_connextdds_common \
        src/**/rmw_connextddsmicro \; do[ -d "$d" ] && touch "$d/COLCON_IGNORE"done
      ```  
            - Temporarily bypass the relevant check with placeholder package.sh (does not affect compiled outputs, can be deleted later):  
      ```bash
      for p in rmw_fastrtps_shared_cpp rmw_fastrtps_cpp rmw_fastrtps_dynamic_cpp; domkdir -p /home/root/ros2_humble/install/$p/share/$pprintf '#!/bin/sh\n# placeholder for %s\n' "$p" > /home/root/ros2_humble/install/$p/share/$p/package.sh
      chmod +x /home/root/ros2_humble/install/$p/share/$p/package.sh
      done
      ```  
            - Build Cyclone DDS first, then build `rmw_implementation`, `rcl`:  
      ```bash
      colcon build --symlink-install \
      --packages-select rmw_cyclonedds_cpp \
      --cmake-args -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTING=OFF
    
      colcon build --symlink-install \
      --packages-select rmw_implementation \
      --cmake-args -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTING=OFF
    
      colcon build --symlink-install \
      --packages-select rcl \
      --cmake-args -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTING=OFF -DRMW_IMPLEMENTATION=rmw_cyclonedds_cpp
      ```  
            - Continue the build  
            - After resolving the above issues, continue with the build:  
      ```bash
      # Continue the build (skip Fast DDS & Connext; disable testing to speed up and reduce dependencies)
      colcon build --symlink-install \
      --cmake-args -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTING=OFF \
      --packages-skip \
      rmw_fastrtps_shared_cpp rmw_fastrtps rmw_fastrtps_cpp rmw_fastrtps_dynamic_cpp \
      rmw_connextdds rmw_connextdds_common rmw_connextddsmicro
      ```
    

Environment variable setup

After the compilation is complete, you need to set up the environment variables to use ROS 2:

export ros2_source=$PWDecho -e "source ${ros2_source}/ros2_humble/install/setup.bash" >> $HOME/.bashrc
source $HOME/.bashrc

Note: ros2_source is the location of the ros2_humble directory, i.e., the ROS 2 workspace created in step 2 of the installation steps.

Usage testing

Examples

• Open a terminal and run the C++ talker example:

ros2 run demo_nodes_cpp talker

• Open another terminal and run the Python listener example:

ros2 run demo_nodes_py listener

Verification

After executing these two commands, you should see messages from the talker side:

ros2 run demo_nodes_cpp talker
[INFO] [1728966840.691346935] [talker]: Publishing: 'Hello World: 1'
[INFO] [1728966841.691537928] [talker]: Publishing: 'Hello World: 2'
[INFO] [1728966842.691572879] [talker]: Publishing: 'Hello World: 3'
[INFO] [1728966843.691563207] [talker]: Publishing: 'Hello World: 4'
[INFO] [1728966844.691568120] [talker]: Publishing: 'Hello World: 5'

And messages from the listener side:

ros2 run demo_nodes_py listener
[INFO] [1728966840.716456921] [listener]: I heard: [Hello World: 1]
[INFO] [1728966841.698002748] [listener]: I heard: [Hello World: 2]
[INFO] [1728966842.697675740] [listener]: I heard: [Hello World: 3]
[INFO] [1728966843.697643318] [listener]: I heard: [Hello World: 4]
[INFO] [1728966844.697551980] [listener]: I heard: [Hello World: 5]

This indicates that both C++ and Python APIs are functioning correctly.